.\" Copyright (c) 2002-2020 Julien Nadeau Carriere <vedge@csoft.net>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd August 21, 2002
.Dt AG_WINDOW 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.0
.Sh NAME
.Nm AG_Window
.Nd agar window system
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
.\" IMAGE(http://libagar.org/widgets/AG_DriverGLX.png, "Multiple Agar windows")
The
.Nm
object describes an Agar window, the base container for Agar widgets.
The
.Xr AG_Widget 3
objects form a tree structure attached to a parent
.Nm .
Agar windows are attached to a parent
.Xr AG_Driver 3
which provides a bridge between the Agar GUI system and the user's preferred
graphics platform / backend.
.Pp
Widgets can be attached to the
.Nm
object itself (it will behave like a standard, vertical
.Xr AG_Box 3 ) .
Agar's standard toolkit includes a variety of other container widgets, such as
.Xr AG_Box 3 ,
.Xr AG_Fixed 3 ,
.Xr AG_Pane 3 ,
.Xr AG_Notebook 3
and
.Xr AG_Scrollview 3 .
.Pp
The dimensions of new Agar windows is best determined automatically (using
recursive widget size requests which take resolution, font sizes, etc. into
account).
Agar widgets are expected to set a proper default size whenever
it can be determined automatically, or otherwise provide a suitable
application-level API for "size hints".
.Pp
Newly created windows (as returned by
.Fn AG_WindowNew )
must be made visible using
.Fn AG_WindowShow .
.Pp
Windows are destroyed by a single call to
.Xr AG_ObjectDetach 3 .
This effectively puts the window in a garbage-collection queue (the actual
freeing of resources will occur only after the end of the current event
processing cycle).
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Xr AG_Widget 3 ->
.Nm .
.Sh INTERFACE
.nr nS 1
.Ft "AG_Window *"
.Fn AG_WindowNew "Uint flags"
.Pp
.Ft "AG_Window *"
.Fn AG_WindowNewNamed "Uint flags" "const char *format" "..."
.Pp
.Ft "AG_Window *"
.Fn AG_WindowNewNamedS "Uint flags" "const char *name"
.Pp
.Ft "AG_Window *"
.Fn AG_WindowNewUnder "AG_Driver *drv" "Uint flags"
.Pp
.Ft "void"
.Fn AG_WindowSetCaption "AG_Window *win" "const char *format" "..."
.Pp
.Ft "void"
.Fn AG_WindowSetCaptionS "AG_Window *win" "const char *text"
.Pp
.Ft "void"
.Fn AG_WindowSetIcon "AG_Window *win" "AG_Surface *surface"
.Pp
.Ft "void"
.Fn AG_WindowSetCloseAction "AG_Window *win" "AG_WindowCloseAction action"
.Pp
.Ft "void"
.Fn AG_WindowSetSideBorders "AG_Window *win" "int pixels"
.Pp
.Ft "void"
.Fn AG_WindowSetBottomBorder "AG_Window *win" "int pixels"
.Pp
.Ft "void"
.Fn AG_WindowSetPosition "AG_Window *win" "enum ag_window_alignment alignment" "int tiling"
.Pp
.Ft "int"
.Fn AG_WindowMove "AG_Window *win" "int xRel" "int yRel"
.Pp
.Ft "void"
.Fn AG_WindowSetGeometry "AG_Window *win" "int x" "int y" "int w" "int h"
.Pp
.Ft "void"
.Fn AG_WindowSetGeometryRect "AG_Window *win" "AG_Rect rect" "int bounded"
.Pp
.Ft "void"
.Fn AG_WindowSetGeometryAligned "AG_Window *win" "enum ag_window_alignment alignment" "int w" "int h"
.Pp
.Ft "void"
.Fn AG_WindowSetGeometryAlignedPct "AG_Window *win" "enum ag_window_alignment alignment" "int wPct" "int hPct"
.Pp
.Ft "void"
.Fn AG_WindowSetGeometryMax "AG_Window *win"
.Pp
.Ft "void"
.Fn AG_WindowSetMinSize "AG_Window *win" "int w" "int h"
.Pp
.Ft "void"
.Fn AG_WindowSetMinSizePct "AG_Window *win" "int pct"
.Pp
.Ft "int"
.Fn AG_WindowSetOpacity "AG_Window *win" "float opacity"
.Pp
.Ft "void"
.Fn AG_WindowSetFadeIn "AG_Window *win" "float fadeTime" "float fadeIncr"
.Pp
.Ft "void"
.Fn AG_WindowSetFadeOut "AG_Window *win" "float fadeTime" "float fadeIncr"
.Pp
.Ft "void"
.Fn AG_WindowSetZoom "AG_Window *win" "int zoomLvl"
.Pp
.Ft "void"
.Fn AG_ZoomIn "void"
.Pp
.Ft "void"
.Fn AG_ZoomOut "void"
.Pp
.Ft "void"
.Fn AG_ZoomReset "void"
.Pp
.Ft "void"
.Fn AG_WindowMaximize "AG_Window *win"
.Pp
.Ft "void"
.Fn AG_WindowUnmaximize "AG_Window *win"
.Pp
.Ft "void"
.Fn AG_WindowMinimize "AG_Window *win"
.Pp
.Ft "void"
.Fn AG_WindowUnminimize "AG_Window *win"
.Pp
.Ft void
.Fn AG_WindowAttach "AG_Window *winParent" "AG_Window *winChld"
.Pp
.Ft void
.Fn AG_WindowDetach "AG_Window *winParent" "AG_Window *winChld"
.Pp
.Ft void
.Fn AG_WindowMakeTransient "AG_Window *winParent" "AG_Window *winTrans"
.Pp
.Ft void
.Fn AG_WindowPin "AG_Window *winParent" "AG_Window *winToPin"
.Pp
.Ft void
.Fn AG_WindowUnpin "AG_Window *win"
.Pp
.Ft void
.Fn AG_WindowUpdate "AG_Window *win"
.Pp
.nr nS 0
The
.Fn AG_WindowNew
function creates a new Agar window using the default
.Xr AG_Driver 3 ,
returning a pointer to the newly created
.Nm
or NULL on failure.
If the default driver is a single-window driver, the new Agar window is
attached to the
.Ft AG_Driver
object.
If the default driver is a multiple-window driver, a new
.Ft AG_Driver
object instance is created for the new window.
See the
.Sx FLAGS
section below for a description of the available
.Fa flags
options.
.Pp
The
.Fn AG_WindowNewNamed
variant creates an Agar window with a unique name identifier.
If a window of the same name exists,
.Fn AG_WindowNewNamed
only moves the focus to that window, and returns NULL.
The name may contain any printable character, except
.Sq / .
.Pp
The
.Fn AG_WindowNewUnder
variant creates a new window and attaches it to an alternate
.Xr AG_Driver 3
instance
.Fa drv .
.Pp
The
.Fn AG_WindowSetCaption
function sets the text displayed by the titlebar (if there is one).
If the string exceeds
.Dv AG_LABEL_MAX
bytes in length, it is truncated.
.Pp
The
.Fn AG_WindowSetIcon
function configures an alternate icon for the window.
This icon will be used by Agar's internal window manager whenever the window
is minimized.
The given surface will be duplicated and rescaled if necessary.
.Pp
.Fn AG_WindowSetCloseAction
sets the action to perform on "window-close":
.Bl -tag -width "AG_WINDOW_IGNORE "
.It AG_WINDOW_HIDE
Hide the window.
This is the default for named windows created with
.Fn AG_WindowNewNamed .
.It AG_WINDOW_DETACH
Detach and destroy the window.
This is the default for anonymous windows created with
.Fn AG_WindowNew .
.It AG_WINDOW_IGNORE
Ignore the close request.
.El
.Pp
To perform a different action, a custom event handler routine can be
set for the "window-close" event (see the
.Sx EVENTS
section).
.Pp
.Fn AG_WindowSetSideBorders
sets the thickness of the left and right window borders in pixels.
.Fn AG_WindowSetBottomBorder
sets the thickness of the bottom border.
The exact interpretation of this setting is theme-specific.
The default for side borders is 0 (no side borders).
If the
.Fa win
argument is NULL, the defaults are set.
.Pp
The
.Fn AG_WindowSetPosition
function moves a window to a standard position, per the specified
alignment.
Possible values for the
.Fa alignment
argument are:
.Bd -literal
 AG_WINDOW_TL  AG_WINDOW_TC  AG_WINDOW_TR
 AG_WINDOW_ML  AG_WINDOW_MC  AG_WINDOW_MR
 AG_WINDOW_BL  AG_WINDOW_BC  AG_WINDOW_BR
.Ed
.Pp
The special value
.Dv AG_WINDOW_ALIGNMENT_NONE
leaves the choice of the initial window position up to the underlying
window manager (possibly Agar itself, or an external WM).
.Pp
If the
.Fa tiling
argument is 1, the
.Dv AG_WINDOW_TILING
flag is set (see
.Sx FLAGS
section).
With tiling enabled, the WM will try to avoid overlap between existing windows.
.Pp
.Fn AG_WindowMove
moves the window to a new position
.Fa xRel ,
.Fa yRel
relative to the window's current position.
.Pp
.Fn AG_WindowSetGeometry
moves/resizes a window to the specific position and geometry, given
in pixels.
If a value of -1 is passed for
.Fa w
or
.Fa h ,
the window's default (or current) geometry is preserved.
.Pp
The
.Fn AG_WindowSetGeometryRect
variant of
.Fn AG_WindowSetGeometry
accepts a
.Xr AG_Rect 3
argument.
The
.Fa bounded
argument specifies whether the window should be limited to the available
view area.
.Pp
The
.Fn AG_WindowSetGeometryAligned
variant assigns the window a specific size in pixels and positions it
according to the specified window alignment (see description of
.Fn AG_WindowSetPosition
for the possible values).
The parameters of
.Fn AG_WindowSetGeometryAlignedPct
are given in percentage of current view area instead of pixels.
Calling these functions with an argument of
.Dv AG_WINDOW_ALIGNMENT_NONE
is a no-op.
.Pp
The
.Fn AG_WindowSetGeometryMax
variant sets the geometry to the size of the display (without setting the
.Dv AG_WINDOW_MAXIMIZED
flag).
.Pp
The
.Fn AG_WindowSetMinSize
routine sets the minimum window size in pixels.
.Fn AG_WindowSetMinSizePct
sets the minimum window size in percentage of the requested (computed) size.
.Pp
.Fn AG_WindowSetOpacity
configures an overall per-window opacity (for compositing WMs).
The argument can range from 0.0 (transparent) to 1.0 (opaque).
This function is not available in integer-only builds.
.Pp
For windows with the
.Dv AG_WINDOW_FADEIN
or
.Dv AG_WINDOW_FADEOUT
flags,
.Fn AG_WindowSetFadeIn
and
.Fn AG_WindowSetFadeOut
can be used to configure the fade timing parameters.
During fade-in, the window opacity will be repeatedly incremented by
.Fa fadeIncr ,
over a total period of
.Fa fadeTime
(in seconds).
This feature is not available in integer-only builds.
.Pp
The
.Fn AG_WindowSetZoom
function sets the zoom level of the window.
The
.Fn AG_ZoomIn ,
.Fn AG_ZoomOut
and
.Fn AG_ZoomReset
functions set the zoom level for the currently focused window.
It is customary to assign
.Xr AG_GlobalKeys 3
shortcuts to these functions.
.Pp
.Fn AG_WindowMaximize
and
.Fn AG_WindowMinimize
maximizes and minimizes the window, respectively.
.Fn AG_WindowUnmaximize
and
.Fn AG_WindowUnminimize
does the opposite.
.Pp
The
.Fn AG_WindowAttach
function registers
.Fa winChld
as a child window dependent of
.Fa winParent .
Detaching the parent window (using
.Xr AG_ObjectDetach 3 )
will cause dependent child windows to be detached implicitely.
Child windows also inherit the style properties from their parent.
The
.Fn AG_WindowDetach
function detaches the window from its parent window.
.Pp
.Fn AG_WindowMakeTransient
registers
.Fa winTrans
as a dependent and transient window for
.Fa winParent .
The effects of transient window state are dependent on the underlying
window system and window manager.
Under Motif, transient windows have no titlebar buttons.
Under TWM, transient windows are created without requesting that the user
select an initial geometry.
Detaching
.Fa winParent
(using
.Xr AG_ObjectDetach 3 )
will cause
.Fa winTrans
to be detached implicitely.
.Pp
The
.Fn AG_WindowPin
function "pins"
.Fa winToPin
to the parent window
.Fa winParent .
If the parent window is moved, the pinned window will be displaced along
with it.
.Fn AG_WindowUnpin
unpins the given window.
.Pp
The
.Fn AG_WindowUpdate
function updates the coordinates and geometries of all widgets attached to
.Fa win .
.Fn AG_WindowUpdate
should be called following
.Xr AG_ObjectAttach 3
or
.Xr AG_ObjectDetach 3
calls made in event context, or manual modifications of the
.Va x ,
.Va y ,
.Va w ,
.Va h
fields of the
.Nm
structure.
Also see:
.Xr AG_WidgetUpdate 3 .
.Sh DRIVER / EVENT LOOP INTERFACE
The following functions should be called only from application-specific
event loops, or low-level driver code.
The standard
.Xr AG_EventLoop 3
invokes them internally.
.Pp
.nr nS 1
.Ft void
.Fn AG_WindowDraw "AG_Window *win"
.Pp
.Ft void
.Fn AG_WindowDrawQueued "void"
.Pp
.Ft void
.Fn AG_WindowProcessQueued "void"
.Pp
.nr nS 0
The
.Fn AG_WindowDraw
function renders the specified window (by calling the
.Fn renderWindow
operation of the associated
.Xr AG_Driver 3 ) .
Calls to
.Fn AG_WindowDraw
must be made in GUI rendering context, between
.Xr AG_BeginRendering 3
and
.Xr AG_EndRendering 3 .
.Pp
.Fn AG_WindowDrawQueued
redraws any window marked as
.Va dirty
since the last redraw.
.Pp
The
.Fn AG_WindowProcessQueued
routine processes any queued
.Xr AG_ObjectDetach 3 ,
.Xr AG_WindowShow 3
or
.Xr AG_WindowHide 3
operation.
.Sh VISIBILITY
.nr nS 1
.Ft void
.Fn AG_WindowShow "AG_Window *win"
.Pp
.Ft void
.Fn AG_WindowHide "AG_Window *win"
.Pp
.Ft int
.Fn AG_WindowIsVisible "AG_Window *win"
.Pp
.Ft void
.Fn AG_WindowLower "AG_Window *win"
.Pp
.Ft void
.Fn AG_WindowRaise "AG_Window *win"
.Pp
.nr nS 0
.Fn AG_WindowShow
makes a window visible and broadcasts the "widget-shown" event to
.Fa win
and its children.
.Pp
.Fn AG_WindowHide
makes a window invisible and broadcasts the "widget-hidden" event to
.Fa win
and its children.
.Pp
Note that
.Fn AG_WindowHide
keeps the window and its resources in memory.
To destroy a window and release its resources, one should use
.Xr AG_ObjectDetach 3 .
.Pp
.Fn AG_WindowIsVisible
returns the current visibility status of a window.
A value of 0 means the window is invisible, 1 means it is visible.
.Pp
.Fn AG_WindowLower
lowers the window to the bottom of the stack.
.Pp
.Fn AG_WindowRaise
raises the window to the top of the stack so that it is not obscured by
other sibling windows.
.Sh FOCUS STATE
The focus state controls the default filtering of events as well as the
behavior and cosmetic appearance of some widgets.
See the
.Dq FOCUS STATE
section of
.Xr AG_Widget 3
for details.
.Pp
.nr nS 1
.Ft void
.Fn AG_WindowFocus "AG_Window *win"
.Pp
.Ft int
.Fn AG_WindowFocusNamed "const char *name"
.Pp
.Ft int
.Fn AG_WindowFocusAtPos "AG_DriverSw *drv" "int x" "int y"
.Pp
.Ft "AG_Window *"
.Fn AG_WindowFind "const char *name"
.Pp
.Ft "AG_Window *"
.Fn AG_WindowFindFocused "void"
.Pp
.Ft "int"
.Fn AG_WindowIsFocused "AG_Window *win"
.Pp
.Ft "void"
.Fn AG_WindowCycleFocus "AG_Window *win" "int reverse"
.Pp
.Ft "void"
.Fn AG_CloseFocusedWindow "void"
.Pp
.nr nS 0
The
.Fn AG_WindowFocus
function sets the focus on the given window.
If the currently focused window has the
.Dv AG_WINDOW_KEEPABOVE
flag set, this function becomes a no-op.
The focus change may not be immediate depending on the underlying graphics
system.
A
.Sq window-gainfocus
event is posted to the window object after the focus change has occurred.
If an argument of NULL is passed to
.Fn AG_WindowFocus ,
any planned change in focus is cancelled.
.Pp
.Fn AG_WindowFocusNamed
calls
.Fn AG_WindowFocus
on the window of the given name and returns 0 on success or -1 if the window
was not found.
.Pp
.Fn AG_WindowFocusAtPos
looks for a window at the specified coordinates in pixels, in the video
display associated with the given single-display driver
.Fa drv
(see
.Xr AG_DriverSw 3 ) .
If a window is found,
.Fn AG_WindowFocus
is called on it and 1 is returned.
Otherwise, 0 is returned.
.Pp
.Fn AG_WindowFind
searches all
.Xr AG_Driver 3
instances for a named window a returns a pointer to
it on success or NULL if none was found.
.Pp
.Fn AG_WindowFindFocused
returns a pointer to the window currently holding input focus,
or NULL if there are none.
.Fn AG_WindowIsFocused
returns 1 if the window is currently holding focus, otherwise 0.
.Pp
.Fn AG_WindowCycleFocus
places the focus over the widget following (or preceeding if
.Fa reverse
is 1) the widget currently holding focus inside of
.Fa win .
By default, Agar maps the "TAB" key to this function.
.Pp
The
.Fn AG_CloseFocusedWindow
routine requests closure of the currently focused window, if any.
.Sh MISCELLANEOUS
.nr nS 1
.Ft "AG_Window *"
.Fn AG_About "void"
.Pp
.Ft "void"
.Fn AG_ViewCapture "void"
.Pp
.nr nS 0
.Fn AG_About
generates an "About Agar GUI" dialog box with copyright information
for the Agar GUI library and core fonts (from
.Pa gui/license.txt ) .
.Pp
.Fn AG_ViewCapture
is only available with single-window drivers.
It dumps the contents of the display surface to
.Pa ~/.<progname>/screenshot/.
.Sh STRUCTURE DATA
For the
.Ft AG_Window
object:
.Bl -tag -width "AG_Window *parent "
.It Ft Uint flags
Option flags (see
.Sx FLAGS
section below).
.It Ft int wmType
Window manager hint describing window function
(see
.Sx WINDOW MANAGER HINTS
below).
.It Ft int visible
Visibility flag (1 = visible, 0 = hidden).
Read-only (see
.Fn AG_WindowShow
and
.Fn AG_WindowHide ) .
.It Ft int dirty
Redraw flag.
If set to 1, the window will be redrawn as soon as possible.
.It Ft AG_Titlebar *tbar
Pointer to the associated
.Xr AG_Titlebar 3
widget, or NULL if the window has no titlebar.
Read-only.
.It Ft int wReq, hReq
Ideal window geometry in pixels, as last computed from the
.Fn size_request
operation of its attached widgets.
Read-only (see
.Xr AG_WidgetSizeReq 3 ) .
.It Ft int wMin, hMin
Suggested minimum window geometry in pixels.
Read-only (use
.Fn AG_WindowSetMinSize ) .
.It Ft AG_Window *parent
Pointer to parent window, or NULL if there isn't any.
Read-only (see
.Fn AG_WindowAttach
and
.Fn AG_WindowDetach ) .
.It Ft TAILQ subwins
List of dependent child windows.
Read-only (see
.Fn AG_WindowAttach
and
.Fn AG_WindowDetach ) .
.It Ft AG_Icon *icon
Pointer to the floating
.Xr AG_Icon 3
object if we are using Agar's internal window manager, NULL otherwise.
Read-only.
.El
.Sh WINDOW MANAGER HINTS
The
.Va wmType
field of
.Nm
hints at the function of the window.
This setting is used by underlying WMs to tweak window appearance and behavior
details.
The values correspond to those specified in Extended Window Manager Hints
(EWMH) version 1.4.
.Bd -literal
enum ag_window_wm_type {
	AG_WINDOW_WM_NORMAL,        /* Normal, top-level window */
	AG_WINDOW_WM_DESKTOP,       /* Desktop feature */
	AG_WINDOW_WM_DOCK,          /* Dock or panel feature */
	AG_WINDOW_WM_TOOLBAR,       /* Toolbar torn off from main window */
	AG_WINDOW_WM_MENU,          /* Pinnable menu window */
	AG_WINDOW_WM_UTILITY,       /* Persistent utility window (e.g.,
	                               a palette or a toolbox). */
	AG_WINDOW_WM_SPLASH,        /* Introductory splash screen */
	AG_WINDOW_WM_DIALOG,        /* Dialog window */
	AG_WINDOW_WM_DROPDOWN_MENU, /* Menubar-triggered drop-down menu */
	AG_WINDOW_WM_POPUP_MENU,    /* Contextual popup menu */
	AG_WINDOW_WM_TOOLTIP,       /* Mouse hover triggered tooltip */
	AG_WINDOW_WM_NOTIFICATION,  /* Notification bubble */
	AG_WINDOW_WM_COMBO,         /* Combo-box triggered window */
	AG_WINDOW_WM_DND            /* Draggable object */
};
.Ed
.Sh FLAGS
For the
.Ft AG_Window
object:
.Bl -tag -width "AG_WINDOW_NOUPDATERECT "
.It AG_WINDOW_TILING
If no explicit window position is specified, choose a default position
using a tiling WM algorithm.
This method honors the preferred window alignment, and also attempts to
avoid overlap with other tiling windows.
Non-tiling windows are ignored in the calculation.
.It AG_WINDOW_FADEIN
Enable smooth fade-in for compositing WM.
.It AG_WINDOW_FADEOUT
Enable smooth fade-out for compositing WM
(only applies to hide operation, not detach).
.It AG_WINDOW_MAXIMIZED
Window is currently maximized (read-only).
.It AG_WINDOW_MINIMIZED
Window is currently minimized (read-only).
.It AG_WINDOW_KEEPABOVE
Stay on top of other windows.
.It AG_WINDOW_KEEPBELOW
Stay below other windows.
.It AG_WINDOW_DENYFOCUS
Don't automatically grab focus in response to a
.Sq mouse-button-down
event in the window area.
.It AG_WINDOW_MODAL
Place window in foreground and prevent other windows from receiving input
events until the modal window is closed.
If the modal window is transient (see
.Fn AG_WindowMakeTransient ) ,
then it is modal for its parent window, otherwise it is application-modal.
.It AG_WINDOW_NOBACKGROUND
Don't fill the window background prior to rendering its contents.
.It AG_WINDOW_MAIN
Break from
.Xr AG_EventLoop 3
if this window gets destroyed.
Multiple windows may set this flag, in which case the break will occur
whenever the last window is closed.
.It AG_WINDOW_NOUPDATERECT
Disable automatic updating of the video region corresponding to the
window area (applicable to framebuffer-based graphics drivers only)
.It AG_WINDOW_NOTITLE
Create a window without a titlebar.
Under some WMs, this may imply
.Dv AG_WINDOW_NOBORDERS .
.It AG_WINDOW_NOBORDERS
Don't draw decorative window borders.
Under some WMs, this may imply
.Dv AG_WINDOW_NOTITLE .
.It AG_WINDOW_PLAIN
Create a completely undecorated window (alias for
.Dv AG_WINDOW_NOTITLE
and
.Dv AG_WINDOW_NOBORDERS ) .
.It AG_WINDOW_NOHRESIZE
Disable horizontal window resize control.
.It AG_WINDOW_NOVRESIZE
Disable vertical window resize control.
.It AG_WINDOW_NORESIZE
Alias for
.Dv AG_WINDOW_NO[HV]RESIZE .
.It AG_WINDOW_NOCLOSE
Disable window close button in titelbar.
.It AG_WINDOW_NOMINIMIZE
Disable minimize button in titlebar.
.It AG_WINDOW_NOMAXIMIZE
Disable maximize button in titlebar.
.It AG_WINDOW_NOBUTTONS
Alias for
.Dv AG_WINDOW_NOCLOSE ,
.Dv AG_WINDOW_NOMINIMIZE
and
.Dv AG_WINDOW_NOMAXIMIZE .
.It AG_WINDOW_HMAXIMIZE
Keep window scaled to the display width.
.It AG_WINDOW_VMAXIMIZE
Keep window scaled to the display height.
.It AG_WINDOW_NOMOVE
User is not allowed to move the window.
.It AG_WINDOW_NOCURSORCHG
Deny any cursor change requested by widgets attached to this window.
This flag is automatically set whenever a window hidden, and cleared a
window is made visible.
.El
.Sh EVENTS
The GUI system may send
.Nm
objects the following events:
.Bl -tag -width 2n
.It Fn window-close "void"
Request to close the window.
Set by
.Fn AG_WindowSetCloseAction .
The default is to
.Em hide
the window (for anonymous windows created by
.Fn AG_WindowNew )
or to
.Em detach
the window (for those created by
.Fn AG_WindowNewNamed ) .
It is safe for a handler to ignore the request or to create new
windows (e.g., confirmation dialogs) in response.
.It Fn window-detached "void"
The window has been successfully detached (as per a previous
.Xr AG_ObjectDetach 3
request).
.It Fn window-shown "void"
The window is now visible.
.It Fn window-hidden "void"
The window is no longer visible.
.It Fn window-enter "void"
The cursor has entered the window area.
.It Fn window-leave "void"
The cursor has left the window area.
.El
.Sh EXAMPLES
The following code fragment creates an Agar window containing a label
and a row of buttons.
It will be positioned and dimensioned automatically:
.Bd -literal -offset indent
AG_Window *win;
AG_Box *box;

win = AG_WindowNew(0);
AG_LabelNew(win, 0, "Hello!");
box = AG_BoxNewHoriz(win, AG_BOX_EXPAND);
{
	AG_ButtonNew(box, 0, "Foo");
	AG_ButtonNew(box, 0, "Bar");
	AG_ButtonNew(box, 0, "Baz");
}
AG_WindowShow(win);
.Ed
.Pp
The following code fragment creates an empty Agar window with a green
background, centers it and sets an explicit size of 320x240:
.Bd -literal -offset indent
AG_Window *win;

win = AG_WindowNew(0);
AG_SetStyle(win, "background-color", "green");
AG_WindowSetGeometryAligned(win, AG_WINDOW_MC, 320, 240);
AG_WindowShow(win);
.Ed
.Sh SEE ALSO
.Xr AG_Cursor 3 ,
.Xr AG_Icon 3 ,
.Xr AG_Intro 3 ,
.Xr AG_View 3 ,
.Xr AG_Widget 3
.Sh HISTORY
The
.Nm
system first appeared in Agar 1.0.
In Agar 1.6.0, the
.Fn AG_WindowFind
call was added and
.Fn AG_WindowNewSw
was renamed
.Fn AG_WindowNewUnder .
.Fn AG_WindowSetPadding
and
.Fn AG_WindowSetSpacing
were deprecated in favor of the "padding" and "spacing" style attributes.
